Skip to main content

DH APP/API Migration Guide

Application Upgrade: V4/V5.x → V5.4

1. Application Versions​

The following table summarizes the capabilities introduced across different application versions.

VersionDescription
V4Error messages and logs were not displayed on the application screen.
V5 – V5.3.xError messages and logs are displayed on the frontend. Abort and Cancel operations are also supported.
V5.4Modules can be configured directly from the application screens, enabling screen-driven configuration without backend intervention.

2. Objective​

The objective of this document is to describe the approach for upgrading the DH Application from V4 or any V5.x version up to V5.3.x to V5.4.

This approach is applicable to all environments:

  • SIT
  • UAT
  • PROD

The upgrade significantly reduces dependency on the backend (Rust) team for routine configuration activities by enabling configuration directly through the application.

2.1 Benefits​

The V5.4 release provides the following advantages:

2.1.1 Simplified Stream Configuration​

  • Stream configuration can be performed directly through the application screens.
  • Eliminates the need for manual backend configuration.

2.1.2 Reduced Backend Dependency​

  • Routine configuration changes no longer require assistance from the backend (Rust) team.

2.1.3 Easier Maintenance​

  • Configuration updates can be performed directly from the frontend.
  • Backend scripts do not need to be executed for routine changes.
  • Reduces turnaround time for post-production configuration updates.

3. Upgrade Approach​

There are two supported approaches for upgrading the application. Approach 1 is recommended.

3.1 Approach 1 – Deploy a New Application Instance (Recommended)​

Deploy a new application instance alongside the existing environment using a separate database schema.

Characteristics:

  • A new application instance is created.
  • A separate database schema is provisioned.
  • Both old and new environments remain operational during the upgrade.
  • The new environment is fully validated before cutover.
  • The existing environment remains unchanged until validation is complete.
  • After successful validation, the old environment can be decommissioned.

Note

Additional ports must be configured for the Orchestrator, Executors, and Application Server. A new database schema must also be provisioned.

3.2 Apporach 2 – Upgrade the Existing Application​

Upgrade the existing application and database schema in place.

Characteristics:

  • No additional infrastructure is required.
  • Existing application and database are upgraded directly.
  • Simpler deployment process.
  • Rollback is comparatively more complex.
  • Suitable when provisioning additional infrastructure is not feasible.

4. Upgrade Procedure​

The following steps are common to both upgrade approaches.

Step 1 – Synchronize UAT and PROD

Ensure that the UAT and PROD environments are synchronized in terms of:

  • Configuration
  • Data

This minimizes inconsistencies during the migration process.

Validate both environments before proceeding.

Step 2 – Upgrade the Database

Execute the incremental database upgrade script to migrate the schema to V5.4.

The script:

  • Applies schema changes incrementally.
  • Preserves existing data.
  • Avoids data loss during the upgrade.

After execution:

  • Verify row counts.
  • Validate key business data.

Step 3 – Deploy the DH PROD Release

Deploy the DH PROD release containing the required V5.4 modules.

Ensure that:

  • The correct release version is deployed.
  • Only the required modules are installed.
  • Unnecessary components are not deployed.

Step 4 – Select the DH Configuration Approach

Choose one of the following approaches.

Option A – Migrate DH Configuration to the Frontend (Recommended)

Recreate the DH configuration using the frontend screens.

Characteristics:

  • All DH configurations are maintained through the application.
  • Backend configuration is no longer required.
  • Recommended for long-term maintenance.

Option B – Reuse Existing Backend CF File

Reuse the existing CF file generated from the backend.

Steps:

  • Use the existing CF file.
  • Configure the CF metadata in the Input Definition screen.
  • Use the configured metadata in downstream modules.

Characteristics:

  • Faster migration.
  • DH configuration remains partially dependent on the backend.

Step 5 – Upgrade the PROD Environment

After validating the selected approach in UAT:

  • Follow the same approach for PROD.
  • Do not change the migration strategy between UAT and PROD.
  • Validate the upgraded PROD environment before proceeding.

Step 6 – Perform Full Migration

Once both environments are upgraded to V5.4:

  • Perform a complete migration.
  • Validate migrated data.
  • Execute sanity testing.
  • Resolve any discrepancies before completion.

Step 7 – Perform Incremental Migration

Incremental migration is used after the initial full migration.

Characteristics:

  • Migrates only frontend changes performed after the previous migration.
  • Backend configuration changes are not migrated automatically.

Important

If DH configuration continues to reside on the backend (using either Option A or Option B), all backend changes must continue to be handled by the Rust Team.

5. Clients with a SIT Environment​

For clients with a SIT environment, the same upgrade process applies.

Migration flow:

SIT → UAT → PROD

This ensures that all changes are validated before deployment to production.

6. Step Ownership​

The following table identifies the activities involved in the upgrade process. Update the Owner column according to your project responsibilities.

StepActivityOwner
1Synchronize UAT and PROD
2Upgrade the database to V5.4
3Deploy the DH PROD release
4aMigrate DH configuration from Backend to Frontend
4bReuse the Backend CF File
5Upgrade the PROD environment
6Perform Full Migration
7Perform Incremental Migration
8Route backend DH changes through the Rust Team (if applicable)

7. Best Practices​

  • Prefer Way 1 whenever infrastructure permits.
  • Validate all changes in UAT before upgrading PROD.
  • Use the same migration approach across all environments.
  • Perform a full migration before initiating incremental migrations.
  • Validate migrated data after each migration activity.
  • Route backend DH configuration changes through the Rust Team whenever backend configuration is still in use.